Languguage OS 2/Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO/language/embedded/mcu332/bccterm.arc/BCCTERM.DOC

Text File | 1989-12-11 | 13KB | 280 lines

 This file contains important information on the installation and operation
 of BCCTERM, written by:
                         Richard Soja,
                         Micro Application,
                         Motorola Semiconductors Ltd,
                         East Kilbride,
                         Scotland.

 It can be freely distributed without charge.
 Its functionality has been checked, but I would be pleased to hear of any
 problems you find, or any enhancements you think may be useful.

 Contents
 --------
 1. Introduction
 2. Installing BCCTERM
 3. Running BCCTERM
 4. I/O register help files

 1. Introduction
 ---------------
 BCCTERM is an MSDOS-based terminal emulator with special features to
 enhance the operation of 32Bug, the monitor on Motorola's 68332 Business
 Card Computer (BCC).
 As the special features are almost completely non-intrusive, BCCTERM can
 be used where any standard terminal emulator is needed.
 The special features provide the following:

 1.1 Formatted memory dump or memory modify of 68332 I/O registers.
 ------------------------------------------------------------------
 The standard hexadecimal display of I/O registers by the 32Bug monitor is
 augmented by displaying the registers in a labelled bit field manner.
 In memory modify mode, the register can be editted in binary or hexadecimal,
 using the left and right arrow keys, within a bordered edit window.

 The format and labelling of the bit fields is completely defined by a user
 specified file call BCCTERM.FMT. See section 2.2 for details.
 If the file does not exist, this feature is inactive.
 If the file exists, the feature can be toggled off and on by pressing
 the F2 key.

 In addition, if a help file is found when in register edit mode, the contents
 of the file can be displayed by pressing the F1 key, and then scanned with
 the up and down cursor control keys. Simultaneously, the left and right arrow
 keys maintain bit field editting of the register contents.
 To close a help window, press the Esc key.
 The help file is identified by possessing the same name as the selected
 register (up to the first 8 significant characters), with the extention .HLP

 e.g. The help file for register QMCR is QMCR.HLP

 If no help file is associated with the selected register, then the message
 'no help' is displayed on the edit window border.

 IMPORTANT NOTES
 ---------------
 i)
 The characters '=','v','^' and '.' are used by 32Bug to control the operation
 of the memory modify command. These characters also can be used while in the
 register edit window. Note that they have immediate effect, rather than having
 to wait for a carriage return to execute. The BCC user manual has more details
 of their function.
 ii)
 Under certain circumstances, when the 32Bug message 'NO MATCH' appears,
 it may be necessary to press the Esc key to exit a register edit window.
 If this is done, no data value is sent to the monitor, and normal, unformatted
 monitor control is restored.

 1.2 Symbolic entry of register address.
 ---------------------------------------
 The address of any register, (or any memory mapped location for that
 matter) can be entered symbolically. To select symbolic entry mode, a
 special key must first be pressed. The key can be user defined, in file
 BCCTERM.CFG, but defaults to the key '[' (left square bracket). See section
 2.1 for details of BCCTERM.CFG.
 Symbolic entry is terminated by a space, comma, semicolon, carriage return
 or any arithmetic operator. This means that symbols can be included in
 arithmetic operations.

 e.g. md ticr+4

 1.3 I/O Register Name and Address Cross Reference
 -------------------------------------------------
 Pressing the F1 key while in normal terminal emulation mode will display a
 short form list of 68332 register names and corresponding addresses, along
 with a brief description. The data for this list is obtained from the user
 defined file BCCTERM.FMT - See section 2.2 for details.

------------------------------------------------------------------------------

 2. Installing BCCTERM
 ---------------------
 Three files are supplied: BCCTERM.EXE
                           BCCTERM.CFG
                           BCCTERM.FMT

 The file BCCTERM.EXE is the executable portion of the terminal emulator.
 BCCTERM.CFG is a configuration file, and BCCTERM.FMT is the register format
 file. As both .CFG and .FMT files are normal text files, they can be printed
 or editted by most word processors.

 Copy all three files into the same directory and ensure that the directory
 is either the current working directory, or its path name is in MSDOS's PATH
 list.

 2.1 Configuring BCCTERM
 -----------------------
 Before running BCCTERM, check the BCCTERM.CFG file. It contains the following
 BCCTERM parameters:

 PORT=COM1
 This determines which PC COM port is to be used.
 The only current alternative is PORT=COM2

 BAUD=9600
 This determines the COM port's baud rate.
 The possible range is BAUD=30 to BAUD=38400.

 sym_switch='['
 This defines the character used to switch to symbolic entry. All characters
 typed in after the sym_switch character and up to the symbolic entry
 terminating character will be trapped by BCCTERM, which will then try to
 resolve the symbol to a value, using the data in the file BCCTERM.FMT.
 If successful, BCCTERM outputs the value to the COM port.
 sym_switch can equate to any single character delimited by single quotes, or
 an immediate symbol followed by the ASCII value of the required character.

 e.g. sym_switch=#3
 This example will make Ctrl-C the symbolic entry switch character.

 IMPORTANT NOTES:
 ----------------
 i)
 There must be no spaces on either side of the '=' symbol in the parameter
 definitions. If BCCTERM detects any errors in the .CFG file, it will abort
 and display an appropriate error message.

 ii)
 If BCCTERM cannot find its .CFG file, it will default to the following
 values:
         PORT=COM1
         BAUD=9600
         sym_switch='['

 2.2 The Register Format File - BCCTERM.FMT
 ------------------------------------------
 This file contains the symbolic names, hexadecimal addresses and various
 formatting information for the 68332 I/O registers.
 The file is a normal ASCII text file, and can be user modified if necessary.
 Each register has a block of associated data fields. An example block follows:

 S:TPU Register Block
 N:TMCR
 A:00FFFE00
 C:    |Prescalers|
 C:STOP|TCR1  TCR2| EMU  T2CG  STF  SUPV  PSCK  Unused  IARBID
 B:  X   XX    XX    X     X    X     X     X     XX     XXXX
 E:

 The S: field identifies the start of the block. The text which follows the S:
 is optional, but if it exists, it is displayed in the description field of the
 short form register list (when key F1 is pressed).
 The N: field defines the symbolic name of the register.
 The A: field defines the register's literal address as received by BCCTERM
 from the 32Bug monitor on the BCC. Note that this address must be an exact
 representation of the address from 32Bug, inclusive of all leading zeroes.
 Alternatively this field can be specified with a start address and an end
 address, separated by a single character.
 e.g.  A:00FFFD00-00FFFD1F

 This causes any address within the specified range to use the same I/O
 register format. (This form is use to display the QSM queues).

 The C: field defines a comment line which is displayed on the terminal screen
 when BCCTERM finds a match between the address from 32Bug and the address in
 the A: field.
 Note that each register can have up to 6 comment lines.
 The B: field defines the locations, identified by the letters X, where the
 value of the register bits (0 or 1) are to be placed. Each X is replace from
 right to left until all Xs are filled or the data value has been exhausted.
 This means that if an 8 bit value is returned by 32Bug to a 16 bit BCCTERM
 format, then only the rightmost 8 bits will be filled. The 8 leftmost bits
 will retain the X character.
 The E: field identifies the end of the block.

 Note: The B: key word can be replaced or augmented by an H: key word, which
 will replace each X from right to left, with the hexadecimal value of the
 register. This means that register data can be displayed in either binary or
 hex or both simultaneously.
 However, because the register edit mode of BCCTERM permits only a single edit
 line, it selects the last specified B: or H: field within the block. The other
 field becomes display only.
 Ensure that each register format block starts with an S: field and ends with
 an E: field, otherwise unpredictable operation may result.

------------------------------------------------------------------------------

 3. Running BCCTERM
 ------------------
 Once all three files, described above, have been installed in the required
 directory, and the BCCTERM.CFG file optionally modified, from the MSDOS
 prompt, type in: BCCTERM

 The monitor will start up and connect to the port and at the baud rate
 specified in the BCCTERM.CFG file (or default to COM1, 9600 baud if .CFG does
 not exist).
 Other default settings for BCCTERM are that the special register formatting
 feature is turned on, and data logging is turned off.
 The keys Esc, F1, F2, F3 and F4 provide control of BCCTERM. They function as
 follows:
 Esc: Quit BCCTERM
 F1 : Display Short Form 68332 Register List. (Explained in Section 1.3)
 F2 : Toggle Register Formatting off or on.   (Explained in Section 1.1)
 F3 : Execute MSDOS command or shell to MSDOS. A command is requested in an
      edit window. If the window is left blank, then BCCTERM shells to MSDOS.
      To return from MSDOS to BCCTERM, type EXIT.
      N.B. For this function to work, COMMAND.COM must exist in the current
      drive's root directory, or alternatively, the environment variable,
      COMSPEC, must be set to the full path name of the COMMAND.COM file.

      e.g. COMSPEC=C:\DOS\COMMAND.COM

      The environment variable should be added to your AUTOEXEC.BAT file.

 F4 : Toggle Data Logging on or off. If data logging is off when this key is
      pressed, then a file name is requested in an edit window. The default
      name of BCCTERM.LOG is offered. When an active data logging session is
      turned off, the log file is closed. Re-starting a logging session with
      the same file name will erase all previously logged data. Shelling to
      MSDOS with the F3 key will not close a log file if logging is active.

 IMPORTANT NOTES
 ---------------
 i)
 The edit windows displayed by the F3 or F4 keys use the following edit keys:
 left arrow  - move cursor left one character
 right arrow - move cursor right one character
 Del         - delete character at cursor position
 Ctrl End    - delete all characters from cursor position to end of line
 Ins         - Toggle insert mode on or off.
               (Insert mode identified by blocked cursor)
 Backspace   - delete character to left of cursor
 Return      - close window and execute function
 Esc         - close window but don't execute function

 ii)
 Two control key sequences provide additional functions to BCCTERM. These are:
 Ctrl B      - sends 20mS break on COM port.
 Ctrl V      - displays a register edit window for test purposes only.
               (Doesn't need connection to BCC hardware).
 In normal terminal emulator mode, all other keys are transmitted directly to
 the COM port.

 3.1 Alternate .CFG and .FMT files
 ---------------------------------
 If BCCTERM is executed without any parameters, at run time, it searches for
 BCCTERM.CFG, BCCTERM.FMT and any .HLP files in the following directories in
 order:

  i) current directory
 ii) directory where BCCTERM.EXE is located

 However, an alternate set of .CFG and .FMT files may be used by BCCTERM, by
 including a single parameter when invoking BCCTERM. The parameter is then used
 as the base name of the .CFG and .FMT files.

 e.g. The MSDOS command: BCCTERM MYTERM

 will result in BCCTERM searching for MYTERM.CFG and MYTERM.FMT using the same
 search criteria as above.
 This means that BCCTERM can be executed with different configurations of PC
 ports and register format files.

 4. I/O Register Help Files
 --------------------------
 Documentation not yet prepared.

 -------------------==================================---------------------